Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / qbprojct.arc / QBPROJCT.DOC < prev next >

Wrap

Text File | 1987-09-29 | 43.8 KB | 1,189 lines

┌─────────────────────────────────────┐ │ ▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄ ▄▄▄▄▄▄▄ │ │ ▐ ▌ ▐ ▌ ▐ ▌ │ │ ▐ ▌ ▐ ▌ ▐ ▌ │ │ ▐ ▌ ▐ ▌ ▐ ▌ │ │ ▐ ▌ ▐▀▀▀▀▀▀▀▀▌ ▐▀▀▀▀▀▀▀ │ │ ▐ ▌ ▐ ▌ ▐ │ │ ▐ ▌ ▐ ▌ ▐ │ │ ▐ uick ▄ ▌ ▐ asic ▌ ▐ roject │ │ ▀▀▀▀▀▀▀▀▀▀▄ ▀▀▀▀▀▀▀▀ │ └─────────────────────────────────────┘ (c) Daniel T. Travison Jr., 1987 P.O. Box 165 Burnt Hills, NY 12027 GEnie D.Travison FidoNet 107/810 (Dave Bauer) Hotel Henge (518)399-3073 10pm-10am EST distributed by FBN Systems ALL RIGHTS RESERVED D I S C L A I M E R ┌───────────────────────────────────────────────────────────┐ │ The author makes no warranties expressed or implied │ │ as to the quality or performance of this program. │ │ The author will not be held liable for any direct, │ │ indirect, incidental or consequential damages resulting │ │ from the use of this program. │ │ Your use of this program constitutes your agreement to │ │ this disclaimer and your releasing the author from any │ │ form of liability or litigation. │ └───────────────────────────────────────────────────────────┘ QBProject (c) Daniel T. Travison Jr. 1987 Introduction: Quick Basic is a powerful compiler providing many features that make Basic a flexible tool for daily use. In addition, the interactive programming environment and debugger greatly ease the common chores during the development and testings stages. However, I have found 2 limiting features in this package and hope this program may provide solutions to both. The first is the editor. After using fast PC level programer's editors as well as several main frame editors I found the editor proved rather primitive when extensive editing is required. Normally this is not a major problem but it is awkward to have to shell to DOS then load an editor. The second area provides no support and involves the managing of program development. There is no make facility provided to manage the compile and link steps. This is notable when using the separate compilation method for compiling stand alone programs. What can be annoying is when the user has other systems that provide these facilities yet is forced to use the 'long hand' method of writing batch files when using basic. QBProject attempts to address these 2 specific areas by providing a full screen 'fill in the blanks' input screen, saving compile and link requirements to 'project' files and the ability to use the editor of your choice. An extended version is in the works at this time to provide dependency checking as well as a directory interface for editing and managing the related source files. Memory Requirements: QBProject does not require any additional memory over what is normally available to compiler. All compile and link steps are performed 'outside' the program. Specifically, a batch files are created to execute the desired function and the program is ended. A flag file is used to store temporary values when returning to the program after the batch file is run. I will give more details later under the compile notes. A point to note is the editor is called using a shell to DOS. This proved to be a much faster approach but does limit the memory available to the editor. If you commonly edit large source files and can not load them when shelling from the program the most obvious approach is to break the source file into separate 'include' files and reference them all from a main routine. The project manager uses such a logical layout at the source file level. I have a primary file called QBPROJCT.BAS with six include files for initialization, screen routines, file routines, batch routines, etc. With a multiple file editor this makes a very flexible and convenient setup. All include files are named Page 1 QBProject (c) Daniel T. Travison Jr. 1987 QBPXXXXX.INC to provide logical grouping by file name. Other than this specific case, you should have no problems with memory and will not be penalized for memory when compiling or linking. Files: In order to run the project manager correctly you will need two files to start. The first is a batch file called QBP.BAT. The second is QBPROJCT.EXE. The batch file contains the following lines: ECHO OFF CLS QBPROJCT QBPSTART The first three lines are self-explanatory. The fourth line is the name of the batch file that the project manager creates to perform the different compile and link operations. For the project manager to perform as designed you MUST start it with this batch file and it MUST be called QBP.BAT. There are 4 other files that the project manager will create. The first is an actual project file and will have an extension of .PRJ. This contains all the information relating to a specific project and there will be one for each project. In addition, the file QBPROJCT.PRJ is used for storing default settings. This is explained later in the setup procedures. The second file is QBP.ENV. This is simply a 1 record file containing the name of the current project. Whenever the program is exited or a compile/link is executed, this file will be updated. It is not required since it is created whenever needed. The third file is QBPSTART.BAT. This file contains the actual commands for executing a link or compile step. When exiting the project manager this will contain a single line setting the current prompt. If the project manager is started using qbprojct.exe instead of qbp.bat, this batch file does not get executed correctly. This file is also created and/or updated as needed so it is not necessary that it be present at start up. The fourth is QBPROJCT.ERR. This file contains all messages generated by the various compile and link options. The file is viewed using the ERROR option on the EDIT menu. Page 2 QBProject (c) Daniel T. Travison Jr. 1987 Environment Settings/Usage: The project manager uses the environment for two separate functions. The first is to read in the default color settings. The environment label required is QBP= . This should be formatted as follows: QBP=aabbcc where: aa = a 2 digit value for the foreground color with valid values being 00 to 15. bb = a 2 digit value for the background color with valid values being 00 to 07. cc = a 2 digit value for the screen border color with valid values of 00 to 15. These numbers MUST be expressed as two digits each and all three MUST be included for the project manager to interpret them correctly. Values of nine or less will require a zero in front of it. (IE: 01 02 03 .... 09) The second use of the environment is for the path pointing to your library files. Since Microsoft's Link checks the environment for the name LIB, this environment name is set each time a compile or link is executed to ensure the libraries are located. The setting for this is based on the value entered in the field LIBRARY PATH on the Linker menu. The primary reason for this approach is to keep the link command line as short as possible. If your libraries are not in the default directory then this field MUST be entered in the setup. Keep in mind that the batch files for compile and link manually set this value. Setup: There is no specific setup requirements for the project manager. However, you do have the capability of creating a default project file called QBPROJCT.PRJ. When the project manager is run without the QBP.ENV file being present it looks for QBPROJCT.PRJ and loads it. If it is not found in the default directory then it is created using various default values and is then loaded. This file will also be loaded whenever the FILE CLEAR option is selected. To modify this file to contain any settings you wish to be default, then either load it specifically or erase the file QBP.ENV before running QBP.BAT. At this point you may change any settings and re-save the project file. When starting a new project, simply load this file and make any necessary changes. Page 3 QBProject (c) Daniel T. Travison Jr. 1987 Directory Usage: > QBPROJCT.EXE: This can be accessed in one of three ways: 1: located in the default directory. 2: located in a directory listed in the environment path setting. 3: Modify the file QBP.BAT so that the line QBPROJCT is changed to [drive:][path]QBPROJCT. ie: d:\utility\QBPROJCT > *.PRJ, QBPROJCT.PRJ, QBP.ENV, QBPSTART.BAT: these files MUST be located in the default or current directory. > QBP.BAT: This file can be located in any directory found in the path setting. > QB.EXE: This file must be in the current/default directory or located in a directory listed in the path setting. > *.LIB: Any libraries required by the linker must be located in the current directory or in the directory indicated in the LIBRARY PATH setting of the project manager. This includes BCOMXX.LIB. > EDITOR: The editor you select for the project manager can be accessed one of three ways: 1: located in the default directory. 2: located in a directory listed in the environment path setting. 3: The path can be specifically stated in the project manager when entering the EDITOR NAME field in the form [drive:][path]program.ext ie: if you use an editor called EDIT.COM and it is located on drive B in the utility subdirectory then you would enter the following for the editor name: B:\UTILITY\EDIT or B:\UTILITY\EDIT.COM > LINK.EXE: This program must be in the current/default directory or a directory listed in the path environment setting. The project manager uses the name LINK in the link step for the name of the linker. If your linker has a different name than you must either copy it using LINK for the name (LINK.COM or LINK.EXE) or just rename it. Page 4 QBProject (c) Daniel T. Travison Jr. 1987 The following is a quick reference to the layout of QBProject's menu structure. Below it you will find the menu expanded with descriptions of the various options. The menus are only two levels deep to allow access to all options in a minimal number of key strokes. ┌──Edit │ ├─ Source │ ├─ Basic │ ├─ Errors │ └─ Other │ ├──Run │ ├──Basic │ ├─ Primary │ └─ Buffer │ ├──Project │ ├─ Compile │ ├─ Link │ ├─ Both │ ├─ Name │ ├─ Editor │ └─ Description │ ├──Switches │ ├─ Error │ ├─ Resume │ ├─ Event │ ├─ Check │ ├─ Speed │ ├─ Arrays │ ├─ String │ └─ Debug │ ├──Linker │ ├─ Exe │ ├─ Map │ ├─ Switches │ ├─ Object │ ├─ Libraries │ └─ Path │ ├──File │ ├─ Load │ ├─ Save │ └─ Clear │ └──Colors ├─ Foreground ├─ Background ├─ Screen border └─ Values Page 5 QBProject (c) Daniel T. Travison Jr. 1987 The following is an expanded listing of the menu structure with detailed descriptions provided for each option. It follows the same layout as the quick reference on the preceding page. Edit: This option provides all the features for │ editing various text files. │ ├─── Source: Edit the primary source file. │ ├─── Basic: Edit any file in the current directory │ with an extention of .BAS. │ ├─── Errors: Edit the QBPROJCT.ERR file which contains │ a log of all errors and messages generated │ by the last compile/link. │ └─── Other: Edit any file. This allows entering the path as well as file name. Run: Run executable file created by compile/link Basic: This option is used for changing the │ primary filename as well as the │ communications buffer size (if needed) │ ├────Primary: This option is used to set the name of │ the basic source file that will be passed │ to the compiler │ └────Buffer: This is used to set the incoming communications buffer size. The /C:XXXX is ALWAYS set so enter a value for this appropriately if you use the communications ports at all in your program. Please note that if this value is not zero than you should include GWCOM in the object file listing of the linker menu. Page 6 QBProject (c) Daniel T. Travison Jr. 1987 Project: This option provides the 'project level' │ facilities provided by QB-Project. │ ├────Compile: Compile the source file. Do not link. │ This options is designed primarily during │ development when you don't think you will │ get a clean compile but need the error │ listing. │ ├────Link: Link only. Used for linking when │ recompiling is not needed. │ ├────Both: This option will perform both the compile │ and link steps. The link step will not be │ executed if an error occurs in the compile │ step. │ ├────Name: This option is for entering the name of │ the project file to save the project │ information. │ ├────Editor: This option is for providing the name of │ the editor you wish to invoke for the EDIT │ menu options. │ └────Description: This provides a brief description of the current project. Switches: This menu option accesses the menu to set │ the compiler switches. These options work Page 7 QBProject (c) Daniel T. Travison Jr. 1987 │ as toggles. An 'X' will appear in the │ appropriate box after the switch toggled │ to indicate it is on. Pressing the same │ switch option will turn off the switch and │ the 'X' will disappear. For more detail │ on these switches refer to chapter four of │ the Quick Basic reference manual. │ ├────On Error: Toggle the (/x) compiler switch. This │ option should be used whenever an ON ERROR │ GOTO and RESUME or RESUME NEXT statements │ are used. This option provides the same │ capability as the RESUME switch. │ ├────Resume: Toggle the (/e) compiler switch. This │ option is used whenever a RESUME/RESUME │ NEXT statement is used. This option │ provides the same capability as the │ ON ERROR switch. │ ├────Event: Toggle the (/v) compiler switch. This │ option provides EVENT TRAPPING for the │ communications port (ON COM), lightpen (ON │ PEN), light pen (ON TIMER), function keys │ (ON KEY), an the joystick (ON STRIG). │ This option is the same as the CHECK │ option but checks between statements. │ ├────Check: Toggle the (/v) compiler switch. This │ option │ provides for the same statements as listed │ in the EVENT option but checks between │ lines. │ ├────Speed: Toggle the (/q) compiler switch. This │ option will cause the compiler to optimize │ the object code for speed. If it is off, │ then optimization is for size. │ ├────Arrays: Toggle the (/r) compiler switch. This │ option causes arrays to be stored in row │ order. If this option is off, then arrays │ are stored in column order. This is not │ normally changed unless you have a │ specific reason for changing it. (ie: an │ assembler module expects row order instead │ of column order) │ ├────Minimize: Toggle the (/s) compiler switch. This │ option causes quoted strings to be written │ to the object file instead of the symbol. │ It is used when memory overflow errors │ occur when compiling. │ │ Page 8 QBProject (c) Daniel T. Travison Jr. 1987 └───Debug: Toggle the (/d) compiler switch. This option causes the generation of debug code provides line locations for error messages, arithmetic overflow, RETURN without GOSUB checking. The limitation is that it generates a larger and slower executable file. Page 9 QBProject (c) Daniel T. Travison Jr. 1987 Linker: This option is used for entering the │ various information for the link step to │ execute. │ ├────Exe: This is the name to use when link creates │ the executable file. The name of the │ primary source file will be used when this │ field is left blank. │ ├────Map: This is the name of the .MAP file the │ linker produces. The default is NUL which │ results in no .MAP file. │ ├────Switches: This field is used supply any switches │ to be passed to the compiler. Generally │ this is not used but it is provided in │ case any unique conditions require it. │ ├────Object: This field is used to list any additional │ .OBJ files that you wish to include in the │ Link step. The .OBJ file produced by the │ compile step is automatically included │ when linking so you should NOT enter that │ in this field. Also, when using the /c │ switch you should include GWCOM in this │ field. File extensions are not entered on │ this line. If the object file is not in │ the current directory then you may have to │ give the entire path and name for the link │ to operate correctly. │ │ ie:drive:][path]filename.obj │ ├────Libraries: This field is for entering any │ additional .LIB files that are needed in │ the link step. It is not necessary to │ include GWCOM and file extensions are not │ required. If any libraries that are to be │ included are not in the current directory │ and are not in the .LIB directory then you │ may have to give the full │ drive\path\filename.ext. This should also │ be placed AFTER all other libraries so as │ not to 'confuse' the linker. │ └────Path: This field is for entering the drive\path where your .LIB files are located. If all .LIB files are in the current directory then this field may be left blank. You may optionally include the trailing back slash but QBProject will add it if you forget. Page 10 QBProject (c) Daniel T. Travison Jr. 1987 File: This menu option contains the selections │ for loading/saving/clearing the project │ file. │ ├────Load: This option will display a list of all │ .PRJ in the current directory. You may │ move through the list using the UP and │ DOWN arrow keys. HOME will move the │ cursor to the top of the current display. │ END will move the cursor to the bottom of │ the current display. PGUP and PGDN │ display the previous and next pages in the │ list respectively. To select a file to │ load, move the highlight to the file │ desired and press enter. To EXIT without │ loading a file or changing any information │ in memory, press ESCAPE. │ ├────Save: This option is used for saving the │ information in memory to a project file. │ When selected, an input field will be │ displayed on the second line of the screen │ with the current project name as the │ default. You may change the name or │ simply press enter to accept it as is. To │ return to the menu without saving, press │ ESCAPE. If a project file already exists │ with the same name you will be asked if │ you wish to over-write the old file. Press │ Y to over-write and N to abort. │ └────Clear: This option is used to clear the current project file and load the default project configuration. If you have made any changes without saving them you will be prompted to save the current project file. If you select Y for yes then you will be taken through the same steps continue without saving your changes. Page 11 QBProject (c) Daniel T. Travison Jr. 1987 Colors: This menu option contains the selections │ for changing the colors that QBProject │ uses for display. │ ├────Foreground: This option is for changing the │ foreground color. This toggles the │ foreground color through the 16 color │ values available on the CGA card. │ ├────Background: This option is for changing the │ background color. This toggles through │ the 8 background colors available on the │ CGA card. │ ├────Screen Border: This option is for changing the │ border that surrounds the active screen │ display. It toggles through the 16 colors │ available on the CGA card. │ └────Values: This option will display the current settings for the foreground, background, and border colors. These 3 values can be combined to form an environment setting that QBProject will use whenever it is run. QBProject examines the environment each time it is executed for the environment name QBP. It attempts to use the setting for QBP as values for screen colors. To use this feature, toggle through the colors until you find the combination that you wish. Select the VALUES option from the menu to display the actual values for the colors selected. Combine these three values and use them when setting the QBP environment variable. For more information refer to Environment Settings/Usage at the beginning of the documentation. Page 12 QBProject (c) Daniel T. Travison Jr. 1987 Using the Menus: The menu structure provided with QBProject is a form that has become very popular with both novice and advanced users. It is primarily designed to provide a list of options and brief information for these options in a limited area as well as being quick and responsive. This type of menu system is very intuitive and I have attempted to provide the same functionality. Despite the popularity of this type of menu, there is a chance the user may not have encountered it so I will explain how the menus work and how to use it. Those that are familiar can skip this description. The menu occupies the top two lines of the display. The topmost provides a list of the options currently available. Initially, the leftmost option is displayed in reverse video or highlighted. This indicates that this is currently the ACTIVE selection. On the second line (or prompt line) there will be either a description of the ACTIVE selection or a list of words indicating that another menu will be displayed if this option is selected. This prompt line is different for each menu option. The LEFT and RIGHT arrow keys are used to make the other options on the menu the ACTIVE selection. As the active selection is changed the previous selection is displayed in normal text and the new active selection is displayed in reverse video. The prompt line is changed as well to display information for the active selection. An option is selected by either pressing the ENTER (or RETURN) key after highlighting the desired option or by simply pressing the first letter of the option desired. In the later case, it is not necessary to highlight the option before pressing its first letter. The menus 'wrap' so that moving the highlight past the one end of the menu will automatically place it at the opposite end. The HOME and END keys are active as well and move the highlight to the first and last selection in the menu respectively. All menus have an escape option to exit. When at the primary menu, (this is the menu of options displayed when the program is initially started) pressing escape will indicate that you wish to EXIT the program. You will be asked if you wish to exit QBProject. You may reply by press Y for yes or N for no. Pressing N for no will return you to the primary menu. When you have selected an option that displays a new menu, pressing ESCAPE at this new menu will return you to the previous menu. As a final note, when ever an option is selected that requires the user to enter information, the menu will be disabled and/or erased with the cursor being placed in the first position of the field to be entered. In addition, the top two lines may also be used to display useful information to clarify the current function in progress. When the menu is active, the normal cursor will not be displayed. This distinguishes between the 2 active screen modes for QBProject, the MENU mode and the EDIT mode. Page 13 QBProject (c) Daniel T. Travison Jr. 1987 Field Editing: Various options require the user to enter information in a fixed size field. When this occurs, the field will be displayed in reverse video and the cursor will be placed in the first position of the field. All input is restricted to this area. The following is a list of the keys used for editing as well as a description of how these keys operate. Enter (Return): This key is used to indicate acceptance of the information. Simply put, when the information is entered, press ENTER or RETURN when you are finished entering or changing the field. Escape: This key works as an abort key. Pressing this key will restore the field to the value it contained before any changes were made as well as returning you to the menu. Right/Left: These two cursor keys allow you to move around inside the current edit field. The cursor is moved OVER characters and does not erase them. Home/End: These two keys move the cursor to the physical start and end of the current edit field. It does not change any characters. Backspace: This key deletes the character to the right of the cursor. At the same time, it moves the cursor left one position and 'pulls' the rest of the characters from the cursor to the end of the field with it. If the cursor is in the first column of the field, this key does not function. Delete: This key DELETES the character located at the cursor and pulls the characters to the right of the cursor over one position. Control-End: This editing key is invoked by holding down the Control key (Ctrl) and at the same time pressing the END key. It will erase every character from the cursor position to the end of the field. Insert: Currently an INSERT mode is not provided. Page 14 QBProject (c) Daniel T. Travison Jr. 1987 Using the FILE LOAD window: When the FILE option is selected on the primary menu, a new menu is displayed with the options Load, Save, Clear. When the LOAD option is selected, a window will 'pop up' over the middle of the display. This window displays a list of the .PRJ files in the current directory and acts as a window onto the entire list. A maximum of 18 file names can be viewed through this window and QBProject can handle up to one hundred project files. The PAGE UP and the PAGE DOWN keys are used to view other files in the list not currently in the window. These keys will page through the list of file names 18 at a time until the beginning or end of the list has been reached. One file in the display will be highlighted. This highlight is used to select a file to load. The UP and DOWN arrow keys are used to move the highlight within the display window. Using the UP arrow key when the highlight is at the top of the display window will cause the list to scroll down each time the key is pressed. Scrolling stops when the top of the list has been reached. The DOWN arrow key has just the opposite result. When at the bottom of the display window, pressing the DOWN arrow key will cause the list to scroll up each time the key is pressed. Scrolling stops when the bottom of the list has been reached. The HOME and END keys are used to move the highlight to the top and the bottom of the window display respectively. The filenames are not changed, simply the position of the highlight. The ENTER (or RETURN) key is used to select the currently highlighted file for loading. The ESCAPE key follows the normal convention and ABORTS the current function and returns you to the menu. As a final note, while the FILE LOAD window is active, the menu at the top of the screen is erased and information is displayed indicating the use of the keys for selecting a file to load. The Status Line: The status line is the 25th line of the display. It is used to display the current project as well as a SAVE indicator that is turned on when ever changes are made to the information in memory. The project name is located on the left side of the status line. The save flag is on the right. Any time a change is made the word SAVE will appear on the right side of the status line. Saving the project file, clearing the file, or loading a new file will turn this off. Page 15 QBProject (c) Daniel T. Travison Jr. 1987 Dollars and Sense: Basically, we are using the Shareware technique of distribution. This is an honor system where the user is allowed to try the program to determine if the program meets the needs of the user. The program is distributed using local and national BBS systems. This allows the cost of distribution to be minimal while providing an easy method of obtaining the program. It also allows the developer to price the program far below commercial rates since a minimal cost for distribution is incurred. With that aside, we present the dollar side. We are requesting a $10.00 registration fee for the use of QBProject. We have determined this price to be VERY reasonable considering the capabilities provided. This allows the use of QBProject on a single machine. Quantity purchases are available on an individual basis. Now to the Sense. We plan to use QBProject as our primary interface to a number of modules which will enhance the capabilities and provide a total Basic project management system. Each module will be capable of standalone execution but will also provide the ability to interface to QBProject. The following is a list of enhancements scheduled for the near future. *1: Dependency checking based on the date. *2: Directory interface to Manage ALL files related to a particular project . 2: MASM interface. 3: Print capabilities: a: Print all include files with the primary source file. b: Subprogram, Gosub, FN cross reference for ALL files in a project group. 4: Extensive system documetation for ALL files in a project group. * These two options are enhancements to QBPROJCT.EXE itself and will be available in the next major release (v2.0) Any user registering QBProject will be entitled a 50% discount on future MAJOR releases as well as a 50% discount for all standalone modules. Starting with version 2.0, users will be notified of all MAJOR and MINOR releases. Minor upgrades are available to registered users simply by requesting them. Keep in mind, you are allowed these discounts ONLY when registering QBProject itself and not the standalone modules. Page 16 QBProject (c) Daniel T. Travison Jr. 1987 All registration forms should be sent to the following address: FBN Systems P.O. Box 165 Burnt Hills, New York, 12027 (New York residents add 7% sales tax.) Inquires, questions and support can be sent to the above address or through one of the following electronic mediums: GEnie address: D.Travison FidoNet node: 107/810 (Dave Bauer or Dan Travison) (518)477-8260 (10pm to 7am EST) Hotel Henge BBS: (518)399-3073 (10pm - 10am) reply to Dan Travison Page 17